home *** CD-ROM | disk | FTP | other *** search
/ BBS Toolkit / BBS Toolkit.iso / doors_1 / doordr50.zip / DOORDRIV.DOC < prev    next >
Text File  |  1991-10-10  |  44KB  |  1,321 lines
  1.           DoorDriver Door Kit                      By Scott M. Baker
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.                      DoorDriver 5.00 - By Scott M. Baker
  9.  
  10.           Introduction - What is DoorDriver?
  11.           ----------------------------------
  12.               Doordriver is a set of .TPU units designed to be used
  13.           to create "Door" programs in the Turbo Pascal programming
  14.           language. The idea behind DoorDriver is that you
  15.           concentrate on writing your game and let DoorDriver do all
  16.           of the nasty ugly low-level details such as handling
  17.           serial I/O and processing BBS drop files.
  18.               Here are a listing of some of DoorDriver's finer
  19.           features:
  20.  
  21.               * Handles all serial I/O for you. You don't need to
  22.                 know a COM-PORT from a BAUD-RATE - DoorDriver'll do
  23.                 it for you.
  24.  
  25.               * Processes drop file from a variety of bbs systems -
  26.                 RBBS-PC, Wildcat, Spitfire, PC-Board, WWIV,
  27.                 Quickbbs, etc.
  28.  
  29.           Drop Files
  30.           ----------
  31.               Drop Files are the files created by the bulletin board
  32.           software when it goes to run a door. Obviously, the door
  33.           needs to know the user's name, baud rate, com port, etc,
  34.           right? Well, this is where that information goes. The BBS
  35.           creates a "Drop File" containing most information that the
  36.           door needs to operate.
  37.               These drop files vary from BBS software to BBS
  38.           software, although some standards are emerging. For this
  39.           purpose, DoorDriver includes support for several different
  40.           drop file formats.
  41.  
  42.           Overview of Routines
  43.           --------------------
  44.               The procedures, functions, and variables in DoorDriver
  45.           can be categorized into several different groups:
  46.  
  47.               * INPUT [INP]
  48.  
  49.                         Get information from the user who is online.
  50.                         Example: SREAD() which performs the
  51.                         functional equivelant of READLN().
  52.  
  53.               * OUTPUT [OUT]
  54.  
  55.                         Send information to the user. Example:
  56.                         SWRITE() which performs the equivelant of
  57.                         WRITE().
  58.  
  59.               * INFORMATIONAL [INF]
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.           DoorDriver Door Kit                      By Scott M. Baker
  68.  
  69.  
  70.  
  71.  
  72.  
  73.                         Provide information about the user, such as
  74.                         his name, baud rate, etc. Example:
  75.                         USER_FIRST_NAME which stores the current
  76.                         user's first name.
  77.  
  78.                         Informational variables are usually
  79.                         read-only, but some can be written to as
  80.                         well. Use common sense and you should get
  81.                         by.
  82.  
  83.               * CONTROL [CTL]
  84.  
  85.                         Procedures which perform various control
  86.                         functions over how doordriver operates.
  87.  
  88.               In the reference sections of this manual, all
  89.           functions/procedures/etc will be placed in one of these
  90.           categories for your convenience.
  91.  
  92.           (copy "converting your program into a door")
  93.  
  94.           Configuration - The Control File
  95.           --------------------------------
  96.               For the convenience of both the author and the sysops
  97.           who will be running the door, DoorDriver picks up some of
  98.           it's configuration data from a "control file". A control
  99.           file is a plain ASCII file which contains special commands
  100.           and directives to tell DoorDriver how to behave. For
  101.           example, this includes which BBS drop files to use, the
  102.           Sysop's name, etc.
  103.               A Sample control file (DOORDRIV.CTL) is included. You
  104.           may designate any name you wish as the name of the control
  105.           file for your door (for example, my CDRDOOR program uses
  106.           CDRDOOR.CTL; News door uses NEWS.CTL, etc)
  107.               The control file is loaded and processed automatically
  108.           when your program calls "INITDOORDRIVER". (This will be
  109.           described further down).
  110.  
  111.           Command Line Parameters
  112.           -----------------------
  113.               DoorDriver supports several parameters which may be
  114.           specified on the command line. These parameters are
  115.           automatically processed for you when you call
  116.           "INITDOORDRIVER".
  117.  
  118.               "/L"      This tells DoorDriver to load up in LOCAL
  119.           mode. This is good for testing or when a sysop just wants
  120.           to "try out" the door without messing with his BBS setup.
  121.           The "/L" mode will ask the user for his name and run the
  122.           door in local mode.
  123.  
  124.               "/S"      This command will tell doordriver to load up
  125.           in the Sysop FAST local mode. The only difference between
  126.           this and "/L" above is that the sysop is not asked his
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.           DoorDriver Door Kit                      By Scott M. Baker
  134.  
  135.  
  136.  
  137.  
  138.  
  139.           name - it is plucked out of the control file
  140.           automatically.
  141.  
  142.               "/M"      This is a generic maintenance mode. It logs
  143.           into the game with the name "SYSTEM MAINT" in local mode.
  144.           You can use it if your program requires a nightly
  145.           maintenance or something similar.
  146.  
  147.               "/Nx"     (where x is 1..9) This specifies a "node
  148.           number". Some bbs software support multinode environments
  149.           in which you must know the node number of the drop file to
  150.           use. For example, RBBS-PC uses DORINFOx.DEF. If you
  151.           specified "/N2" then doordriver would use DORINFO2.DEF.
  152.  
  153.               "/Pyyy"   This specifies the PATH to the drop files.
  154.           For example, "/PC:\BBS" would tell DoorDriver to look for
  155.           the drop files in C:\BBS.
  156.  
  157.           Reference - Procedures
  158.           ----------------------
  159.  
  160.           INITDOORDRIVER(filen: string);                   [CTL]
  161.  
  162.               This procedure MUST be called before any of
  163.           DoorDriver's features are used. In fact, in most cases it
  164.           should be the first statement that your program executes.
  165.           The FILEN variable specifies the filename of the control
  166.           file that DoorDriver will use (i.e. DOORDRIV.CTL).
  167.               InitDoorDriver does a variety of things including
  168.           loading and processing the control file, reading the drop
  169.           files, setting up serial I/O. It also sets up an "EXIT
  170.           Procuedure" which will automatically close down the serial
  171.           I/O when your program is finished.
  172.  
  173.           DISPLAYFILE(Filen: String);                      [OUT]
  174.  
  175.                This Procedure is usefull in that it will transfer an
  176.           Ascii or Ansi file, and will put "(C)ontinue, (S)top,
  177.           (N)onstop" to stop an Ascii file from scrolling of the
  178.           page and thus allowing the user to read this file at his
  179.           or her own speed.
  180.  
  181.  
  182.           DISPLAY_MACRO(s: string);                        [OUT]
  183.  
  184.                This procedure is used to display a macro-string. The
  185.           macro string is usually contained in the variable
  186.           MACRO_STRING.
  187.  
  188.  
  189.           PROMPT(var s: string; length: integer; hi: boolean); [INP]
  190.  
  191.                The prompt procedure is a high-level string input
  192.           routine. It allows you to specify the maximum length of
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.           DoorDriver Door Kit                      By Scott M. Baker
  200.  
  201.  
  202.  
  203.  
  204.  
  205.           the input string and if HI is set to true, it will hilight
  206.           the input in reverse background. The colors for the prompt
  207.           routine are defined in the control file.
  208.  
  209.  
  210.           RECORD_MACRO(var s: string);                     [INP]
  211.  
  212.                This procedure allows the user to record a macro
  213.           string, up to 255 characters that will be invoked whenever
  214.           the CTRL-N key is pressed. The macro is stored in the
  215.           string variable S. To activate the macro capability, you
  216.           must place the macro into the string variable
  217.           "MACRO_STRING".
  218.  
  219.  
  220.           SCLRSCR;                                         [OUT]
  221.  
  222.                This procedure clears the remote side's and the local
  223.           side's screen.
  224.  
  225.           SCRLEOL;                                         [OUT]
  226.  
  227.                This procedure will clear up to then end of the
  228.           current line. (note: only works when caller has ANSI
  229.           capabilities)
  230.  
  231.  
  232.           SET_FOREGROUND(i: integer);                      [OUT]
  233.  
  234.                The set_foreground procedure sets the current
  235.           foreground color to the one specified by the integer
  236.           variable, i. The color is set both on the local side and
  237.           the remote side if the remote user has ANSI toggled on.
  238.           The acceptable range for the color is 0-15.
  239.  
  240.  
  241.           SET_BACKGROUND(i: integer);                      [OUT]
  242.  
  243.                The set_background procedure sets the current
  244.           background color to the one specified by the integer
  245.           variable, i. The color is set both on the local side and
  246.           the remote terminal if the remote user has toggled his
  247.           ANSI on. The acceptable range for the color is 0-7.
  248.  
  249.  
  250.           SGOTO_XY(x,y: integer);                          [OUT]
  251.  
  252.                Sgoto_xy allows you to position the cursor on the
  253.           local and remote screen. The valid range for X is 1 to 80
  254.           and the valid range for Y is 1 to 24.
  255.  
  256.  
  257.           SREAD_CHAR(var c: char);                         [INP]
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.           DoorDriver Door Kit                      By Scott M. Baker
  266.  
  267.  
  268.  
  269.  
  270.  
  271.                This procedure waits for a character to be pressed
  272.           and then returns that character in the character variable.
  273.           No echoing is performed (i.e. the user will not see the
  274.           key he pressed). If you wish echoing, you must again write
  275.           the character with SWRITE below. This routine is useful
  276.           for writing your own lowlevel readln routines or
  277.           performing "hot-key" operations. It is a direct
  278.           replacement for CH:=READKEY.
  279.  
  280.           SREAD(var s: string);                            [INP]
  281.  
  282.                The sread procedure accomplishes the equivilant of
  283.           the Turbo Pascal procedure READLN. A string is read from
  284.           the user and wher the CR character is obtained, the
  285.           procedure exits with the string stored in the string
  286.           variable, s.
  287.  
  288.  
  289.           SREAD_NUM(var i: integer);                       [INP]
  290.  
  291.                The sread_num procedure is almost identical to the
  292.           sread procedure except it will read an integer variable
  293.           instead of a string. Only the characters 0-9 are allowed
  294.           to be entered by the user. The value returned will be in
  295.           the range of -32768 to +32768.
  296.  
  297.  
  298.           SREAD_NUM_BYTE(var b: byte);                     [INP]
  299.  
  300.                The sread_num_byte procedure is almost identical to
  301.           the sread procedure except it will read an byte variable
  302.           instead of a string. Only the characters 0-9 are allowed
  303.           to be entered by the user. The value returned will be in
  304.           the range of 0 to 255.
  305.  
  306.  
  307.           SREAD_NUM_WORD(var w: word);                     [INP]
  308.  
  309.                The sread_num_word procedure is almost identical to
  310.           the sread procedure except it will read an word variable
  311.           instead of a string. Only the characters 0-9 are allowed
  312.           to be entered by the user. The value returned will be in
  313.           the range of 0 to 65535.
  314.  
  315.  
  316.           SREAD_NUM_LONGINT(var l: longint);               [INP]
  317.  
  318.                The sread_num_longint procedure is almost identical
  319.           to the sread procedure except it will read an longint
  320.           variable instead of a string. Only the characters 0-9 are
  321.           allowed to be entered by the user. The value returned will
  322.           be in the range of -2147483648 to +2147483647.
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.           DoorDriver Door Kit                      By Scott M. Baker
  332.  
  333.  
  334.  
  335.  
  336.  
  337.           SWRITE(s: string);                               [OUT]
  338.  
  339.                The swrite procedure is the equivilant of the Turbo
  340.           Pascal WRITE procedure. Swrite will simultaniously write
  341.           to both the local screen and the remote terminal. No CR/LF
  342.           sequence is added to the end of the string. (note: You may
  343.           also use WRITE(SOUTPUT,s))
  344.  
  345.  
  346.           SWRITELN(s: string);                             [OUT]
  347.  
  348.                The swriteln procedure is the equivilant of the Turbo
  349.           Pascal WRITELN procedure. Swrite will simultaniously write
  350.           to both the local screen and the remote terminal. A CR/LF
  351.           sequence is appended to the end of the string. (note: You
  352.           may also use WRITELN(SOUTPUT,s))
  353.  
  354.           DDASSIGNSOUTPUT(f: text);                        [CTL]
  355.  
  356.                This procedure assigns the simultanious output
  357.           channel to a text file. This is done automatically by
  358.           INITDOORDRIVER to SOUTPUT (i.e. DDASSIGNSOUTPUT(SOUTPUT).
  359.           But, if you wish to assign it to a different file, you may
  360.           do it with this procedure. For example:
  361.  
  362.           DDASSIGNSOUTPUT(my_output_file);
  363.           rewrite(my_output_file);
  364.           writeln(my_output_file,'This will go to both local and '+
  365.                                   'remote.');
  366.  
  367.  
  368.           Reference - Functions
  369.           ---------------------
  370.  
  371.           SKEYPRESSED: Boolean;                            [INF]
  372.  
  373.                SKEYPRESSED will return TRUE if a key has been
  374.           pressed and is waiting to be read and FALSE if no key has
  375.           been pressed. It is the equivelant of Turbo Pascal's
  376.           KEYPRESSED function.
  377.                This also allows the program to pause until the user
  378.           presses a key. When used in a loop like this it stops
  379.           everything until user input occurs.
  380.  
  381.                Repeat Until skeypressed;
  382.  
  383.  
  384.           TIME_LEFT: Byte;                                 [INF]
  385.  
  386.                The time_left function returns the amount of time
  387.           left in minutes. This time is computed automatically by
  388.           doordriver for you.
  389.  
  390.           Reference - Variables
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.           DoorDriver Door Kit                      By Scott M. Baker
  398.  
  399.  
  400.  
  401.  
  402.  
  403.           ---------------------
  404.  
  405.           SOUTPUT: text;                                   [OUT]
  406.  
  407.                This text file is associated with the simultanious
  408.           output channel. It provides an alternate form of IO than
  409.           using swrite/swriteln. To use, simply treat SOUTPUT as it
  410.           were a normal text file. For example,
  411.  
  412.             Writeln(SOUTPUT,'This is a test'); is the same as
  413.           swriteln('This is a test');
  414.  
  415.             When is this useful? When you want to use WRITELN's
  416.           ability to write various data types (i.e. integers, reals,
  417.           etc) or it's ability to format output. For example:
  418.  
  419.             USING SWRITELN: str(integer_data,tempstr);
  420.           swriteln(tempstr);
  421.  
  422.             USING SOUTPUT:  writeln(soutput,integer_data);
  423.  
  424.           ALTKEYS: (see configurable alt key section)
  425.  
  426.           ALTHELP: (see configurable alt key section)
  427.  
  428.           ANSION: boolean;                                 [CTL]
  429.  
  430.               This variable controls whether local output (it has
  431.           nothing to do with remote) will go directly to the local
  432.           screen or if it will be sent through doordriver's
  433.           emulation routine. Since the emulation routine is slow in
  434.           comparison to direct output, this variable is defaulted to
  435.           FALSE. If you want to send your own ANSI codes to the
  436.           screen through SWRITE/SWRITELN, then you will have to set
  437.           this variable to TRUE.
  438.  
  439.           BAUD_RATE: integer;                              [INF]
  440.  
  441.                This variable holds the user's current baud rate.
  442.  
  443.           BBS_SOFTWARE: byte;                              [INF]
  444.  
  445.               The following numbers indicate software names:
  446.  
  447.               0 : Maintenance mode               n/a
  448.               1 : Local-only operation           n/a
  449.               2 : Sysop-fast logon only          n/a
  450.               3 : Qbbs                           DORINFOx.DEF
  451.               4 : Pcboard-12                     PCBOARD.SYS
  452.               5 : WWIV                           CHAIN.TXT
  453.               6 : n/a                            n/a
  454.               7 : Rbbs 16.x                      DORINFOx.DEF
  455.               8 : Phoenix                        EXITINFO.DAT
  456.               9 : WildCat (pre - 3.0)            CALLINFO.BBS
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.           DoorDriver Door Kit                      By Scott M. Baker
  464.  
  465.  
  466.  
  467.  
  468.  
  469.               10: Pcboard-14                     PCBOARD.SYS
  470.               11: DOOR.SYS                       DOOR.SYS
  471.               12: Spitfire                       SFDOORS.DAT
  472.  
  473.  
  474.           BBS_TIME_LEFT: integer;                          [INF]
  475.  
  476.               This holds the amount of time that the user had left
  477.           when he entered the door. It is loaded from the DROP FILE
  478.           by INITDOORDRIVER. Note that this provides the time left
  479.           when the user ENTERED the door, not the current time left.
  480.           The current amount of time left is calculated by the
  481.           function TIME_LEFT.
  482.  
  483.           BOARD_NAME: String[70];                          [INF]
  484.  
  485.                Board_Name hold the current BBS's name that is set in
  486.           the control file.
  487.  
  488.           CHARORIGIN: CharOriginType;                      [INF]
  489.  
  490.                Returns either LocalChar or RemoteChar depending on
  491.           where the last sread_char was received from. This is
  492.           mainly used in the chat routine to set different
  493.           foreground colors for local and remote users.
  494.  
  495.           COM_PORT: byte;                                  [INF]
  496.  
  497.                Contains the current com port that serial output is
  498.           going to. Should be a zero if in local mode.
  499.  
  500.  
  501.           CURRENT_FORGROUND: byte;                         [INF]
  502.  
  503.                This variable stores the current foreground color.
  504.  
  505.  
  506.           CURRENT_BACKGROUND: byte;                        [INF]
  507.  
  508.                This variable stores the current background color.
  509.  
  510.           CURLINENUM: byte;                                [INF]
  511.  
  512.                This variable is used internally to control the more
  513.           prompt. It is incremented when a line of text is sent out.
  514.           When it reaches 24, a <more> is sent. This is of course,
  515.           providing that morechk:=true.
  516.  
  517.                                                            [INF]
  518.           GRAPHICS: byte;
  519.  
  520.               Graphics specifies a text mode:
  521.  
  522.               1 : Ascii - General Text
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.           DoorDriver Door Kit                      By Scott M. Baker
  530.  
  531.  
  532.  
  533.  
  534.  
  535.               2 : Ascii's Extended Graphics and General Text
  536.               3 : Ansi Color and Graphics
  537.               4 : Ansi Color and Graphics and Ansi Music (See
  538.                   Section on ANSI.TPU)
  539.  
  540.           LOCAL: boolean;                                  [INF]
  541.  
  542.               This boolean is alway true if in local mode and false
  543.           if in remote mode.
  544.  
  545.  
  546.           MINTIME: byte;                                   [INF]
  547.  
  548.                (check this - don't know)
  549.  
  550.           MORECHK: boolean;                                [CTL]
  551.  
  552.                This boolean allows you to toggle the more prompts on
  553.           or off. If TRUE, then doordriver will display a "more"
  554.           prompt every 24 lines.
  555.  
  556.  
  557.           NODE_NUM: byte;                                  [INF]
  558.  
  559.                Returns the current Node that the door is running
  560.           under. Defaulted to 1 in a single node system. This
  561.           corresponds directly to the "/Nx" command line parameter.
  562.  
  563.  
  564.           NOTIME: String;                                  [CTL]
  565.  
  566.                (check this)
  567.  
  568.                When the users time limit has been reached this
  569.           string will be displayed then the user will be returned to
  570.           the bbs. This string has a default of "(***TIME LIMIT
  571.           EXCEEDED***)".
  572.  
  573.           STACKED: string;                                 [---]
  574.  
  575.                The Procedure sread and sreadln can have stacked
  576.           commands which is when a user type something in like this:
  577.  
  578.                             "m;101;m;102;m;103;m;104"
  579.  
  580.                Notice the ";"'s throughout the example. well this is
  581.           a stacked command. the ";"'s indicate a seperate
  582.           operation. This allows the user to type in multiple
  583.           operations to preform on one line and not have to go
  584.           through each and every prompt of the door. This can be
  585.           very useful when used in combi- nation with the
  586.           Record_Macro command.
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.           DoorDriver Door Kit                      By Scott M. Baker
  596.  
  597.  
  598.  
  599.  
  600.  
  601.           STATFORE: byte;                                  [CTL]
  602.  
  603.                The status line foreground.
  604.  
  605.  
  606.           STATBACK: byte;                                  [CTL]
  607.  
  608.                The status line background.
  609.  
  610.  
  611.           STATLINE: boolean;                               [CTL]
  612.  
  613.                A status line pops while any door is in operation if
  614.           this boolean is set true. The status line contains the
  615.           user name and the program name an the users time left.
  616.  
  617.  
  618.           SYSOP_FIRST_NAME: string[30];                    [INF]
  619.  
  620.                Returns the first name of the sysop. The name is
  621.           entered into door-driver through the control file.
  622.  
  623.  
  624.           SYSOP_LAST_NAME: string[30];                     [INF]
  625.  
  626.                Returns the last name of the sysop. The name is
  627.           entered into door-driver through the control file.
  628.  
  629.  
  630.           USER_FIRST_NAME: string[30];                     [INF]
  631.  
  632.                Returns the first name of the current user of the
  633.           door program. The user's name is determined from whatever
  634.           door information is passed from the bbs software.
  635.  
  636.  
  637.           USER_LAST_NAME: string[30];                      [INF]
  638.  
  639.                Returns the last name of the current user of the door
  640.           program. The user's name is determined from whatever door
  641.           information is passed from the bbs software.
  642.  
  643.  
  644.           USER_ACCESS_LEVEL: word;                         [INF]
  645.  
  646.                Returns the access level of the user. The user's
  647.           access level is determined from whatever door information
  648.           is passed from the bbs software.
  649.  
  650.  
  651.           PROGNAME: String[60];                            [CTL]
  652.  
  653.                This option must be set by the programmer, preferably
  654.           in the beginning of the door. It sets the name that will
  655.  
  656.  
  657.  
  658.  
  659.  
  660.  
  661.           DoorDriver Door Kit                      By Scott M. Baker
  662.  
  663.  
  664.  
  665.  
  666.  
  667.           be displayed centered on line 25 of the screen. It is
  668.           simply used for cosmetic purposes.
  669.  
  670.  
  671.           MACRO_STRING: string;                            [INF/CTL]
  672.  
  673.                 The contents of this variable are treated as a
  674.           macro. Whenever the user types a CTRL-N, the string will
  675.           be output. The string may be easily recorded with the
  676.           RECORD_MACRO procedure and displayed with the
  677.           DISPLAY_MACRO procedure.
  678.  
  679.  
  680.           SETFORECHECK: boolean; (default=FALSE)           [CTL]
  681.  
  682.                 This variable when set to TRUE will cause DOORDRIV
  683.           to filter out repetetive SET_FOREGROUND() calls. If for
  684.           example, you set the foreground to gray, then set it to
  685.           gray again later while the foreground is still gray, the
  686.           second call would be ignored. This can spare the user from
  687.           the slowdown effects of meaningless, repetetive
  688.           SET_FOREGROUND calls.
  689.  
  690.           Referance - Constants
  691.           ---------------------
  692.           VERSION = 'Version 5.00; 9-18-91'        (LARGE VERSION)
  693.                   = 'Version 5.00S; 9-18-91'       (SMALL VERSION)
  694.  
  695.  
  696.           Reference - Procedure Substitutions
  697.           -----------------------------------
  698.           This section is provided to help you in figuring out which
  699.           doordriver routines you should call to replace turbo's
  700.           standard I/O routines.
  701.  
  702.           READKEY:
  703.  
  704.               Readkey is used in many normal programs to get a
  705.           single character. (i.e. CHAR:=readey). This can be
  706.           replaced by SREAD_CHAR(char);.
  707.  
  708.           WRITELN(xxxx);  (or WRITE(xxxx))
  709.  
  710.               The writeln procedure is probably the most common and
  711.           numerous change that you will have to make. DoorDriver
  712.           provides the SWRITE/SWRITELN procedures to do the job of
  713.           turbo's write/writeln. In addition, the SOUTPUT file is
  714.           also available. Let's take a look at some examples:
  715.  
  716.           Ex 1
  717.           ----
  718.            Convert "writeln('Scott was here!');"
  719.  
  720.               --> swriteln('Scott was here!');
  721.  
  722.  
  723.  
  724.  
  725.  
  726.  
  727.           DoorDriver Door Kit                      By Scott M. Baker
  728.  
  729.  
  730.  
  731.  
  732.  
  733.  
  734.            or --> writeln(soutput,'Scott was here!');
  735.  
  736.           Ex 2
  737.           ----
  738.            int is an integer.
  739.            Convert "write(int);"
  740.  
  741.               --> str(int,tempstr); swrite(tempstr);
  742.  
  743.            or --> write(soutput,int);
  744.  
  745.           Ex 3
  746.           ----
  747.            r is a real.
  748.            Covert "writeln(r:2:2);"
  749.  
  750.               ---> str(r:2:2,tempstr); swriteln(tempstr);
  751.  
  752.            or ---> writeln(soutput,r:2:2);
  753.  
  754.               As you can see, the SWRITE/SWRITELN method is easier
  755.           if you are using string type data, but the
  756.           write(SOUTPUT,xxx) method is better for numerical types.
  757.           You can use whichever you like.
  758.  
  759.  
  760.           CLREOL:
  761.  
  762.               You can replace CLREOL with SCLREOL, but please note
  763.           that it will only work when the caller has ANSI
  764.           capabilities. If the caller doesn't have ansi, then he'll
  765.           get a load of garbage.
  766.  
  767.  
  768.           CLRSCR:
  769.  
  770.               CLRSCR can be directly converted to SCLRSCR. This
  771.           works for either ANSI or non-ANSI users.
  772.  
  773.           GOTOXY(x,y):
  774.  
  775.               GOTOXY(x,y) can be converted into SGOTO_XY(x,y), but
  776.           again, this will only work for ansi users.
  777.  
  778.           READLN(string_variable) ---> SREAD(string_variable)
  779.  
  780.           READLN(integer_variable) ---> SREAD_NUM(integer_variable)
  781.  
  782.           READLN(word_variable) ---> SREAD_WORD(word_variable)
  783.  
  784.           READLN(long_variable) ---> SREAD_LONGINT(long_variable)
  785.  
  786.  
  787.  
  788.  
  789.  
  790.  
  791.  
  792.  
  793.           DoorDriver Door Kit                      By Scott M. Baker
  794.  
  795.  
  796.  
  797.  
  798.  
  799.           REFERENCE - Units
  800.           -----------------
  801.  
  802.               I'll briefly list the included units and what they do
  803.           here. Inside UNITINTR.ARJ you will find the interface
  804.           section of all of DoorDriver's units. Some are commented
  805.           and come are not.
  806.  
  807.               *DOORDRIV.TPU
  808.  
  809.                This is the "large" version of doordriver. It's the
  810.           main unit that you need to use.
  811.  
  812.               *DDANSI.TPU
  813.  
  814.                Contains procedures used by doordriver to display
  815.           ANSI on local screen.
  816.  
  817.               *DDFOSSIL.TPU
  818.  
  819.                Contains procedures used by doordriver to interact
  820.           with fossil drivers.
  821.  
  822.               *DDSCOTT.TPU
  823.  
  824.                Miscellanious procedures used by doordriver.
  825.  
  826.               *REWINDOW.TPU
  827.  
  828.                The remote window routines.
  829.  
  830.               *CFGEDITR.TPU
  831.  
  832.                Configurable editor.
  833.  
  834.               *COMIO.TPU
  835.  
  836.                Medium-level COM I/O used by doordriver.
  837.  
  838.               *ASYNC.TPU/SZASYNC.OBJ
  839.  
  840.                Internal COM routines.
  841.  
  842.               *DDOVR.TPU
  843.  
  844.                Overlayable unit containing code that gets
  845.           information out of bbs drop files (i.e. DORINFOx.DEF, etc)
  846.  
  847.               *DDOVR2.TPU
  848.  
  849.                Overlayable unit that contains code to process
  850.           control file.
  851.  
  852.  
  853.  
  854.  
  855.  
  856.  
  857.  
  858.  
  859.           DoorDriver Door Kit                      By Scott M. Baker
  860.  
  861.  
  862.  
  863.  
  864.  
  865.           REFERENCE - CONFIGURABLE ALT KEYS
  866.           ---------------------------------
  867.               Inside doordriver's SREAD_CH routine (which handles
  868.           all input from the user), doordriver processes ALT-KEY
  869.           combinatations (such as ALT-H, ALT-D, etc). These ALT-KEYs
  870.           activate certain features within doordriver.
  871.               Doordriver includes support to "hook" your own
  872.           procedures into a certain ALT key. when the sysop hits
  873.           that key, whatever procedure you define will be executed.
  874.               DoorDriver defines the variable ALTKEYS as an
  875.           array['A'..'Z'] of pointer. These correspond to ALT-A
  876.           through ALT-Z. To link a procedure into these alt keys,
  877.           you must do the following:
  878.  
  879.               1: Your procedure must be compiled FAR. (i.e. put
  880.                  {$F+} and {$F-} around it)
  881.  
  882.               2: Your procedure must not have any parameters passed
  883.                  to it.
  884.  
  885.               3: You must set the appropriate pointer in ALTKEYS to
  886.                  point to your procedure.
  887.  
  888.               For example:
  889.  
  890.           {$F+}
  891.           PROCEDURE Display_Neato_message;
  892.           begin;
  893.            swriteln('Neat-o! The Alt Keys worked!');
  894.           end;
  895.           {$F-}
  896.  
  897.           PROCEDURE Install_Neato;
  898.           begin;
  899.            ALTKEYS['N']:=@Display_Neato_message; {Hook in the proc}
  900.            new(althelp['N']);                    {create a help
  901.                                                   line}
  902.            althelp^['N']:='Neato!';              {Put in help}
  903.           end;
  904.  
  905.               The procedure INSTALL_NEATO is what installs the
  906.           Display_Neato_Message procedure into the ALT-N key. It
  907.           also does a few other things which may need a little
  908.           explanation:
  909.               The ALTHELP array is an array of ^STRING which
  910.           contains strings which will be displayed in doordrivers
  911.           hot-key help (ALT-H). To create a help string, you have to
  912.           NEW the string, then put the data in. This is not
  913.           absolutely necessary and is only used for cosmetic
  914.           purposes.
  915.               Note: You can also use ALTKEYS to disable or override
  916.           the built in ALT-C (chat), ALT-H (help), and ALT-D (drop
  917.           to dos). For example, ALTKEYS['D']:=Nil would disable drop
  918.           to dos.
  919.  
  920.  
  921.  
  922.  
  923.  
  924.  
  925.           DoorDriver Door Kit                      By Scott M. Baker
  926.  
  927.  
  928.  
  929.  
  930.  
  931.               Now, if you aren't totally confused, I'm real
  932.           surprised.... (grin). The sample program, EDITDEMO sets up
  933.           a configurable editor screen tied to ALT-E.
  934.  
  935.           REFERENCE - ANSI MENU ROUTINES
  936.           ------------------------------
  937.  
  938.                There is an additional TPU file included with the
  939.           doordriver package that includes a user-friendly ANSI-MENU
  940.           handler. The TPU can be called up with the statement "USES
  941.           ANSIMENU". The menu system is accessed by the single
  942.           function:
  943.  
  944.                    CHAR:=GetAnsiMenu(menu_definition_template)
  945.  
  946.                 The menu-definition-template type is declared within
  947.           the unit. It is identical to the structure below:
  948.  
  949.  
  950.                  menutype = record
  951.                              header: string[80];
  952.                              footer: string[80];
  953.                              headercolor,
  954.                              footercolor,
  955.                              optioncolor,
  956.                              desccolor,
  957.                              arrowcolor,
  958.                              bracketcolor: byte;
  959.                              numoptions: byte;
  960.                              options: array[1..20] of string[1];
  961.                              desc: array[1..20] of string[80];
  962.                             end;
  963.  
  964.                 The structure is usually defined by your program as
  965.           a constant. The ANSIMENU procedure interprets this
  966.           strucure and uses it to generate a centered menu. The menu
  967.           options may be selected by using the numeric keypad (the 8
  968.           for up and the 2 for down) or by simply typing the the
  969.           letter of the option. A sample door, NEWS.PAS, is included
  970.           to demonstrate the use of the ansimenu unit.
  971.  
  972.           REFERENCE - DDTERM TERMINAL SUPPORT
  973.           -----------------------------------
  974.           DDTERM support killed! It just didn't accomplish a whole
  975.           lot, so I nuked the support. Sorry if anyone was using it,
  976.           but DDTerm never really has amounted to much over here.
  977.  
  978.  
  979.           REFERENCE - SAMPLE DOORS
  980.           ------------------------
  981.  
  982.               I have included two sample door programs, NEWS.PAS and
  983.           BBSLIST.PAS. These two programs are intended to be an
  984.           example of how doordriver can be used.
  985.  
  986.  
  987.  
  988.  
  989.  
  990.  
  991.           DoorDriver Door Kit                      By Scott M. Baker
  992.  
  993.  
  994.  
  995.  
  996.  
  997.               NEWS.PAS is a program that I once wrote as an online
  998.           news reader for USA Today, Movie Review, and a few other
  999.           electronic magazine services. It's a good demonstration of
  1000.           how to use the ANSIMENU unit, displayfile, and several of
  1001.           DoorDriver's features.
  1002.               BBSLIST.PAS is a bbs list maintainer that I wrote a
  1003.           while back. Like NEWS, it's a good example of the ANSIMENU
  1004.           unit.
  1005.               You are free to use code in these programs if you
  1006.           like, but I do maintain a copyright on those programs. If
  1007.           you do use code, I expect to be "cut in" to whatever
  1008.           extent the code was used. For example, if you developed
  1009.           BBSLIST.PAS into a little more powerful program and
  1010.           started distributing it, I would expect a reasonable
  1011.           portion of whatever profits you make.
  1012.  
  1013.           REFERENCE - IMPORTANT THINGS
  1014.           ----------------------------
  1015.  
  1016.           -> What happens when the user runs out of time, sleep
  1017.           -> disconnects, or drops carrier?
  1018.  
  1019.           Doordriver will HALT. This will cause an immediate
  1020.           termination of the door. If your door needs to save any
  1021.           data then you should use an EXIT PROCEDURE to save the
  1022.           data. For example:
  1023.  
  1024.           {$F+} procedure myexit; {$F-}
  1025.           begin;
  1026.            save_our_data;
  1027.            exitproc:=exitsave;
  1028.           end;
  1029.  
  1030.           {main program}
  1031.           begin;
  1032.            InitDoorDriver......
  1033.            ExitSave:=Exitproc;
  1034.            ExitProc:=@myexit;
  1035.            .......
  1036.           end.
  1037.  
  1038.           This will setup MYEXIT so it is run whenever your program
  1039.           exits for any reason. This is the best way to trapped
  1040.           carrier dropped, out of time, etc.
  1041.  
  1042.           NOTE #1: The carrier, time left, and sleep disconnect are
  1043.           only tested when doordriver is waiting for a keypress
  1044.           (i.e. sread_char, sread, etc)
  1045.  
  1046.           NOTE #2: If checktime=false then DoorDriver will not check
  1047.           to see if the user is out of time.
  1048.  
  1049.           -> How do I use ANSI in my programs?
  1050.  
  1051.  
  1052.  
  1053.  
  1054.  
  1055.  
  1056.  
  1057.           DoorDriver Door Kit                      By Scott M. Baker
  1058.  
  1059.  
  1060.  
  1061.  
  1062.  
  1063.           You can use ANSI by two methods:
  1064.  
  1065.            1) By using the set_foreground, set_background, and
  1066.               sclrscr procedures, you can perform some basic ANSI
  1067.               functions. DoorDriver will automatically enable these
  1068.               fucntions when ANSI is available and disable it when
  1069.               not.
  1070.  
  1071.            2) If you set ANSION:=TRUE, then you can just SWRITE your
  1072.               ansi sequences directly to the screen. When you turn
  1073.               ANSION on, it will slow down screen writes, so it is
  1074.               advisable to do it only when necessary.
  1075.  
  1076.           REFERENCE - CARRIER DETECT
  1077.           --------------------------
  1078.               I am currently writing a door tutorial for Michael
  1079.           Crosson's Carrier Detect Journal. Carrier Detect is a
  1080.           bi-monthly electronic journal produced by Mike and it is
  1081.           quite good.
  1082.               The Door Tutorial that I am writing was started in the
  1083.           September 1991 issue of CD and will continue as long as
  1084.           possible. I have included the september extract of Door
  1085.           Tutorial as DDTUT1.DOC.
  1086.               Issues of Carrier Detect can be found on my bbs.
  1087.  
  1088.  
  1089.           UPDATE HISTORY
  1090.           --------------
  1091.  
  1092.                   Version 2.50:
  1093.  
  1094.            - First Public release
  1095.  
  1096.                   Version 2.55:
  1097.  
  1098.           - DoorDriver screen removed and replaced by a 2-line
  1099.           message.
  1100.  
  1101.           - Small problem with SET_FOREGROUND has been fixed.
  1102.  
  1103.           - The NEWS.DIR file which was left out in previous
  1104.           versions has now been included.
  1105.  
  1106.                   Version 2.60:
  1107.  
  1108.           - Modifications to the ANSIMENU TPU 1) The TPU is now
  1109.           called "ANSIMENU" instead of "ANSIMENUSYSTEM". If your
  1110.           program was using the ansimenu routines, then the "uses"
  1111.           statement must be changed from "uses ansimenusystem" to
  1112.           "uses ansimenu". 2) The function name "ANSIMENU" has been
  1113.           repleaced by "GETANSIMENU". All occurences of the function
  1114.           call <char>:=Ansimenu(<MenuTemplate>) must be changed to
  1115.           <char>:=GetAnsiMenu(<MenuTemplate>).
  1116.  
  1117.  
  1118.  
  1119.  
  1120.  
  1121.  
  1122.  
  1123.           DoorDriver Door Kit                      By Scott M. Baker
  1124.  
  1125.  
  1126.  
  1127.  
  1128.  
  1129.           - DoorDriver title screen/info shrunk even more at users'
  1130.           request.
  1131.  
  1132.                   Version 3.00
  1133.  
  1134.           - Doordriver majorly modified to switch to use of control
  1135.           file rather than the /C configuration.
  1136.  
  1137.           - INITDOORDRIVER(filename) must be called before any of
  1138.           doordrivers routines are used.
  1139.  
  1140.           - SREAD_CHAR was omitted by accident in previous versions
  1141.           of the documentation.
  1142.  
  1143.           - Many new configuration options present in the control
  1144.           file including EGA/VGA support.
  1145.  
  1146.           - Two versions of DoorDriver are now included. DOORDRIV is
  1147.           the normal version with all features included while
  1148.           DOORDRSM is the SMALL version which leaves out the
  1149.           REWINDOW, ALT-KEY, and SYSOP FILTER support. If your
  1150.           program begins to run low on memory, you may wish to
  1151.           consider using DOORDRSM instead of DOORDRIV.
  1152.  
  1153.           - Doordirv.INT has been included in the package and
  1154.           includes the actual interface section of doordriver.
  1155.  
  1156.           - CFGEDITR.TPU has been altered. (See edittest.pas for the
  1157.           new template record structure)
  1158.  
  1159.                   Version 4.00
  1160.  
  1161.           - The DDANSI unit went through a major overhaul - it
  1162.           should now be faster and more error free.
  1163.  
  1164.           - DDTERM support included - see the above section for
  1165.           information.
  1166.  
  1167.           - Both TP5.5 and TP6.0 routines included.
  1168.  
  1169.                   Version 5.00
  1170.  
  1171.           - The actual bbs-information loading code has been moved
  1172.           into DDOVR.TPU. This file may be overlaid if you wish to
  1173.           conserve memory.
  1174.  
  1175.           - Control file processing code moved to DDOVR2.TPU.
  1176.  
  1177.           - SOUTPUT file and DDAssignSOutput(f:text) procedure
  1178.           added.
  1179.  
  1180.           - Added spitfire and Door.sys support.
  1181.  
  1182.           - Removed DDTERM support.
  1183.  
  1184.  
  1185.  
  1186.  
  1187.  
  1188.  
  1189.           DoorDriver Door Kit                      By Scott M. Baker
  1190.  
  1191.  
  1192.  
  1193.  
  1194.  
  1195.  
  1196.           - Changed around the way the configurable ALT-Keys worked.
  1197.           If you were using the old method, please see the above
  1198.           section on configurable alt keys.
  1199.  
  1200.           - Removed the REWindow support routines. They weren't
  1201.           widely used.
  1202.  
  1203.           - Documentation upgraded a lot!
  1204.  
  1205.           Credits
  1206.           -------
  1207.           SCOTT BAKER (myself)
  1208.  
  1209.               Author of DOORDRIVER, NEWS, and ANSIMENU.
  1210.  
  1211.           DERRICK PARKHURST
  1212.  
  1213.               Repairs to the still malfunctioning ANSI.TPU unit.
  1214.               Various work on configurable editor routines.
  1215.               Remote windowing and Windowed chat support.
  1216.               Sysop filter.
  1217.  
  1218.           CARL EVANS (of Vervans War Board)
  1219.  
  1220.               Addition of PC-BOARD 14 support.
  1221.  
  1222.  
  1223.           Copyright
  1224.           ---------
  1225.  
  1226.                  The DOORDRIVER routines are copyrighted by Scott
  1227.           Baker and Derrick Parkhurst. This copyright includes all
  1228.           material contained in this package - TPU modules, PAS
  1229.           files, sample door, Documentation, etc. You are permitted
  1230.           to USE these routines in your own doors if you wish under
  1231.           the following conditions:
  1232.  
  1233.                      1) Any material which you use from this package
  1234.           must not be modified in any way. You can use it, but you
  1235.           can't hack into it.
  1236.  
  1237.                      2) If you intend to use this kit for commercial
  1238.           purposed (this includes SHAREWARE), then you must register
  1239.           it with the author and pay the required minimum
  1240.           registration fee.
  1241.  
  1242.                      3) You MUST include credit to the authors of
  1243.           these routines in your program, documentation, etc.
  1244.  
  1245.           Suggested Registration Fee
  1246.           --------------------------
  1247.               I encourage you to send me whatever you feel
  1248.           doordriver is worth. The minimum that I will consider is
  1249.  
  1250.  
  1251.  
  1252.  
  1253.  
  1254.  
  1255.           DoorDriver Door Kit                      By Scott M. Baker
  1256.  
  1257.  
  1258.  
  1259.  
  1260.  
  1261.           $25 which I feel doordriver is easily worth that much.
  1262.               However, don't feel you are limited to $25. You can
  1263.           send as much as you like. If doordriver is a major part of
  1264.           your program which you could not do without it, then
  1265.           please compensate me for my work. For example, I have a
  1266.           few authors who are sending me a percentage of their
  1267.           profit off their doors as compensation.
  1268.  
  1269.               I encourage you to register this package with the
  1270.           authors if you find it useful to your programming.
  1271.           Registration/donations can be mailed to the following
  1272.           address:
  1273.  
  1274.           Scott M. Baker
  1275.           6431 Tierra Catalina #48
  1276.           Tucson, Az 85718
  1277.  
  1278.                  If you wish to contact the authors of this software
  1279.           for any reason, they may be reached by the address above,
  1280.           or you may log on to our software support bbs:
  1281.  
  1282.           "The Not-Yet-Named bbs"
  1283.  
  1284.           Sysop: Scott Baker
  1285.           NODE #1: (602) 577-3650 1200-9600  (V.32)     1:300/9
  1286.           NODE #2: (602) 577-3419 2400-14400 (USR DUAL) 1:300/29
  1287.  
  1288.  
  1289.  
  1290.  
  1291.  
  1292.  
  1293.  
  1294.  
  1295.  
  1296.  
  1297.  
  1298.  
  1299.  
  1300.  
  1301.  
  1302.  
  1303.  
  1304.  
  1305.  
  1306.  
  1307.  
  1308.  
  1309.  
  1310.  
  1311.  
  1312.  
  1313.  
  1314.  
  1315.  
  1316.  
  1317.  
  1318.  
  1319.  
  1320.  
  1321.